gRPC Provider

High-performance RPC communication for UTCP

The gRPC provider enables UTCP to interact with gRPC services, providing efficient, schema-driven communication with high performance, low latency, and strong typing. This provider is ideal for microservices architectures and high-throughput applications.

Configuration

gRPC providers are configured using the following JSON structure:

{
  "name": "grpc_service",
  "provider_type": "grpc",
  "host": "api.example.com",
  "port": 50051,
  "service_name": "Calculator",
  "method_name": "Add",
  "use_ssl": true,
  "auth": {
    "auth_type": "api_key",
    "api_key": "YOUR_API_KEY",
    "var_name": "x-api-key"
  }
}

Configuration Fields

Field	Required	Description
`name`	Yes	Unique identifier for the provider
`provider_type`	Yes	Must be set to `"grpc"`
`host`	Yes	Hostname or IP address of the gRPC server
`port`	Yes	Port number of the gRPC server
`service_name`	Yes	Name of the gRPC service to call
`method_name`	Yes	Name of the method to call on the service
`use_ssl`	No	Whether to use SSL/TLS for the connection (default: `false`)
`auth`	No	Authentication configuration (if required)
`timeout`	No	Request timeout in seconds (default: `30`)
`proto_file`	No	Path to the protocol buffer definition file

Authentication Options

gRPC providers support several authentication methods:

API Key Authentication

{
  "auth": {
    "auth_type": "api_key",
    "api_key": "YOUR_API_KEY",
    "var_name": "x-api-key"
  }
}

OAuth2 Authentication

{
  "auth": {
    "auth_type": "oauth2",
    "token": "YOUR_ACCESS_TOKEN"
  }
}

TLS Client Certificate

{
  "auth": {
    "auth_type": "tls_client_cert",
    "cert_file": "/path/to/client.crt",
    "key_file": "/path/to/client.key"
  }
}

Tool Discovery

Since gRPC doesn't natively support dynamic discovery, UTCP tools can be discovered through:

gRPC Reflection: If the server supports reflection, query available services and methods
Static Definition: Tool definitions provided in a separate JSON file
Companion HTTP Endpoint: A companion HTTP endpoint at /utcp

{
  "name": "grpc_service",
  "provider_type": "grpc",
  "host": "api.example.com",
  "port": 50051,
  "discovery_url": "https://api.example.com/utcp"
}

The discovery endpoint should return a UTCPManual object as described in the For Tool Providers section.

Examples

Calculator Service

{
  "name": "calculator",
  "provider_type": "grpc",
  "host": "calc.example.com",
  "port": 50051,
  "service_name": "Calculator",
  "method_name": "Add",
  "use_ssl": true,
  "timeout": 10
}

Authenticated Service

{
  "name": "user_service",
  "provider_type": "grpc",
  "host": "users.example.com",
  "port": 443,
  "service_name": "UserService",
  "method_name": "GetUser",
  "use_ssl": true,
  "auth": {
    "auth_type": "oauth2",
    "token": "your_access_token"
  }
}

Best Practices

Performance Optimization

Use connection pooling for high-volume scenarios
Set appropriate timeouts and deadlines
Consider using streaming for large data transfers
Implement proper error handling for gRPC status codes

Schema Management

Ensure client has access to protocol buffer definitions
Version your proto files for backward compatibility
Use descriptive field names and comments

Security

Always use TLS in production environments
Implement proper authentication and authorization
Validate all input data on the server side